Creating Kanzi Studio window plugins

Kanzi Studio plugins extend the functionality of Kanzi Studio and run in Kanzi Studio. Use a Kanzi Studio plugin to:

Automate tasks in Kanzi Studio. For example, to automate tasks that take a lot of time when you do them manually, or the task is prone to errors.
Import and export content from Kanzi Studio. For example, to import or export localization tables in a format not supported by Kanzi Studio.
Create editors that abstract the details and speed up the workflow. For example, to visualize the connections between nodes and resources used in your Kanzi Studio project.

You can present a Kanzi Studio plugin either in a Kanzi Studio window that contains the plugin user interface, or as a command that users can execute from the context menu and run the plugin without a user interface. This topic covers how to create Kanzi Studio window plugins. To learn how to create Kanzi Studio command plugins, see Creating Kanzi Studio command plugins.

The default UI framework for creating Kanzi Studio window plugins is WPF. However, you can use frameworks that run on HTML using WPF's web browser control, or other frameworks by embedding the content using WPF's HwndHost control that hosts a win32 window as an element into WPF content.

Kanzi Studio plugin interface is provided as .NET framework assembly. You can find it in <KanziInstallation>/Studio/Bin/PluginInterface.dll. The plugin interface provides access to data and commands in Kanzi Studio. To develop a Kanzi Studio plugin:

Create the base for a Kanzi Studio plugin. See Creating the base for a Kanzi Studio window plugin.
Build and run your Kanzi Studio plugin. See Building and running a Kanzi Studio plugin.
Debug your Kanzi Studio plugin. See Debugging a Kanzi Studio plugin.
Add functionality to your Kanzi Studio plugin. See Adding functionality to your Kanzi Studio plugin.

To find detailed information about the Kanzi Studio plugin interface see:

Creating the base for a Kanzi Studio window plugin

Kanzi Studio window plugins are plugins that you use in a Kanzi Studio window and have a user interface. For example, use the window plugins to create an editor or to visualize the content in your project.

Here you create the base for a Kanzi Studio window plugin where you then add functionality that extends the functionality of Kanzi Studio.

To create a Kanzi Studio window plugin:

In Visual Studio select File > New > Project and create a Visual C# Class Library.
In the Solution Explorer right-click the project name, select Add > Reference, and add references to files:
1. Select Assemblies > Framework targeting .NET Framework and add the reference to:
  - System.ComponentModel.Composition
  - System.XAML
2. Click Browse... and add the reference to the <KanziInstallation>/Studio/Bin/PluginInterface.dll file.
In the Solution Explorer right-click the project name, select Properties:
- In the Application tab set the Target framework to .NET Framework 4.6.2.
- In the Build tab set the Platform target to x64.
In the Solution Explorer right-click the project name, select Add > User Control and add a User Control (WPF) item.
Open the UserControl1.xaml.cs file and add the using directive for the Kanzi Studio plugin interface:
```
using Rightware.Kanzi.Studio.PluginInterface;
```
Set the UserControl1 class to implement the PluginWindow interface:
1. Change
```
public partial class UserControl1 : UserControl
```
  to
```
public partial class UserControl1 : UserControl, PluginWindow
```
2. Right-click PluginWindow and select Implement Interface.
3. Add the KanziStudio interface to the UserControl1 class. KanziStudio interface is the entry point for operating with the Kanzi Studio plugin API.
```
private KanziStudio studio;
```
In all functions replace this line with the code you want to execute:
```
throw new NotImplementedException();
```
Make sure that your plugin handles all its internal exceptions and does not let them reach the Kanzi Studio interface.
For example, set the functions in the UserControl1 class:
- Add to UserControl1 the studio parameter. This enables you to instantiate the UserControl1 and supply studio as an argument in the Class1.cs file.
```
public UserControl1(KanziStudio studio)
{
    this.studio = studio;
    InitializeComponent();
}
```
- Use the Icon function to set the plugin window icon shown in the top-left corner of the plugin window:
  - Return an empty string to use the Kanzi Studio default plugin icon.
```
get
{
    return "";
}
```
- Use the SerializeState function to save the state of the plugin window. Kanzi Studio calls this function when you close the plugin window. When you open the plugin window again, Kanzi Studio passes the same state as a parameter as it creates the plugin window.
  When set to null, Kanzi Studio does not remember the state of the window.
```
return null;
```
- Use the Title function to set the text you want to show as the title of the plugin window. For example, set it to:
```
get
{
    return "Plugin title";
}
```
- Use the Dispose function to clean up when closing the plugin window. For example, here you can release all resources you use in the plugin, and if your plugin subscribes to any events, unsubscribe these events here. Kanzi Studio calls this function when user closes a plugin window.
  Since in this example there is nothing to clean up, you can leave this function empty.
Open the Class1.cs file and add the using directive for the System.ComponentModel.Composition and the Kanzi Studio plugin interface:
```
using System.ComponentModel.Composition;
using Rightware.Kanzi.Studio.PluginInterface;
```
Set the Class1 class to implement the PluginWindowFactory interface, which you implement in the Class1 class. Kanzi uses this class to create the plugin. Kanzi Studio first gets the factory and defines the name of the plugin, the size of the window, if the plugin has a window, and from where in Kanzi Studio users can launch the plugin.
1. Change
```
public class Class1
```
  to
```
public class Class1 : PluginWindowFactory
```
2. Right-click PluginWindowFactory and select Implement Interface.
Before the definition of the class where you create the plugin, mark the factory class which implements the PluginWindowFactory interface to be the plugin content for Kanzi Studio. This way Kanzi Studio knows that the .dll is a plugin.
```
[Export(typeof(PluginContent))]
```
In all functions replace this line with the code you want to execute:
```
throw new NotImplementedException();
```
Make sure that your plugin handles all its internal exceptions and does not let them reach the Kanzi Studio interface.
For example, set the functions in the Class1 class to:
- Use the CreateWindow function to instantiate the UserControl1 and supply studio as an argument. You added the studio parameter to the UserControl1 in the UserControl1.xaml.cs file.
```
return new UserControl1(studio);
```
- Use the DefaultHeight and DefaultWidth functions to the height and width of the window of your plugin. For example, to make a 400 by 400 pixel plugin window use:
```
get
{
    return 400;
}
```
- Use the CanExecute function to set whether users can launch your plugin, and where they can launch your plugin:
  - When set to false, Kanzi Studio shows the plugin in the main menu and the context menu, but users cannot launch the plugin.
  - When set to true, users can launch the plugin.
  Kanzi Studio provides the KanziStudio object to plugins. The KanziStudio object is the root object for data access and provides the current project, available commands, global undo and redo, and events related to project opening and closing.
  For example, use this to enable the command only when a Kanzi Studio project is open
```
private KanziStudio studio;
public bool CanExecute(PluginCommandParameter parameter)
{
    return this.studio != null && this.studio.Project != null;
}
```
- Use the CommandPlacement function to set the menu name of the plugin, and where you want to show the command to launch the plugin:
  - To show the plugin in the main menu use ContextMenuPlacement.NONE.
  - To show the plugin in the context menus invoked from nodes and resources, and the main menu use ContextMenuPlacement.PROJECT_ITEM.
```
get
{
    return new CommandPlacement("myPluginMenu", ContextMenuPlacement.NONE, false, null);
}
```
- Use the Description function to set a brief description of what your Kanzi Studio plugin does. Kanzi Studio shows this description as a tooltip when a user hovers the mouse pointer over the plugin name in the menu.
```
get
{
    return "A tooltip with short description of what the plugin does.";
}
```
- Use the DisplayName function to show the plugin name in the Kanzi Studio menu where you can launch the plugin.
```
get
{
    return "Plugin display name";
}
```
- Use the Name function to set the internal name of your plugin. Kanzi uses the internal name of the plugin so that you can change the display name of your plugin without additional changes to the plugin.
```
get
{
    return "Internal plugin name";
}
```
- Use the Initialize function to place studio to a member variable.
```
public void Initialize(KanziStudio studio)
{
    this.studio = studio;
}
```
- Add to the Execute function the code you want your plugin to run.
  For example, use this to print Hello world! to the Log window in Kanzi Studio when you run your plugin.
```
studio.Log("Hello world!");
```
Build and run the plugin. See Building and running a Kanzi Studio plugin.

To further develop your Kanzi Studio plugin, see Overview of Kanzi Studio plugin interface and Kanzi Studio plugin interface API reference.

Building and running a Kanzi Studio plugin

To build and run a Kanzi Studio plugin:

In Visual Studio select Build > Build Solution to build the plugin .dll.
Copy the Kanzi Studio plugin .dll to the %ProgramData%\Rightware\<KanziVersion>\plugins directory.
If the plugins directory does not exist in %ProgramData%\Rightware\<KanziVersion>, create it.
Open Kanzi Studio. If Kanzi Studio is already running select File > Import > Reload Kanzi Studio Plugins to load all newly added plugins and to apply the changes made to the plugins. If the Reload Kanzi Studio Plugins menu option is not available, restart Kanzi Studio.

Kanzi Studio loads the plugins and adds them to either the main menu or the context menus invoked from nodes and resources.
In Kanzi Studio select the plugin main menu and select the plugin, or right-click a node in the Project and select the name of your plugin to run your plugin.

Debugging a Kanzi Studio plugin

To debug a Kanzi Studio plugin:

In Visual Studio create and build your Kanzi Studio plugin. See Creating the base for a Kanzi Studio window plugin.
In Windows Explorer create a shortcut from your Kanzi Studio plugin .dll and move the shortcut to %ProgramData%\Rightware\<KanziVersion>\plugins.
By default Visual Studio builds the .dll of your plugin in C:\Users\<UserName>\Documents\Visual Studio 2015\Projects\<ProjectName>\<ClassLibraryName>\bin\Debug or Release directory.
In Visual Studio add the break points where you want to debug your plugin.
In Visual Studio select Debug > Attach to Process ..., in the Available Processes select KanziStudio.exe and click Attach.
In Kanzi Studio if you have the plugin open, close it, select File > Import > Reload Kanzi Studio Plugins to apply the changes you made to the plugin, and run the plugin.

Adding functionality to your Kanzi Studio plugin

After you create the base for a Kanzi Studio window plugin, add functionality to your plugin so that it does something useful. Here you create a plugin that shows the kzb file URL of the currently selected node or resource.

To add functionality to your Kanzi Studio plugin:

Create the base for your Kanzi Studio window plugin. See Creating the base for a Kanzi Studio window plugin.
In Visual Studio open the Visual Studio solution of your plugin and open the class file that implements the PluginWindow interface.
For example, open the UserControl1.xaml.cs class file.

In the class that implements the PluginWindow interface add the code that your plugin executes when you interact with the plugin in the plugin window.
For example, to create a plugin that shows the kzb file URL of the currently selected project item use:

    public partial class UserControl1 : UserControl, PluginWindow
    {
        private KanziStudio studio;

        public UserControl1(KanziStudio studio)
        {
            this.studio = studio;
            InitializeComponent();
            // Subscribe to the SelectionChanged event to find out when the selection of a node or a resource changes.
            studio.SelectionChanged += Studio_SelectionChanged;
            // Set the contents of the plugin window.
            Populate();
        }

        // When the currently selected project item changes, set the contents of the plugin window. 
        private void Studio_SelectionChanged(object sender, EventArgs e)
        {
            Populate();
        }

        // Set the text in the controls that show the name and kzb file URL of the currently selected project item.
        public void Populate()
        {
            var currentSelection = studio.SelectedItems.FirstOrDefault();
            this.selectionTextBlock.Text = (currentSelection != null) ? currentSelection.Name : "< no project item selected >";
            this.kzbUrlTextBox.Text = (currentSelection != null) ? currentSelection.KzbUrl : " ";
        }

        ...

        // Set the title of the plugin window.
        public string Title
        {
            get
            {
                return "Project item kzb file URL";
            }
        }

        ...

        // Dispose of the resources used by the window.
        public void Dispose()
        {
            if (studio != null)
            {
                this.studio.SelectionChanged -= Studio_SelectionChanged;
            }
        }

        ...

    }

In Visual Studio open the XAML file that implements the layout of the window plugin and add the content you want to show in the window.
For example, open the UserControl1.xaml file and change

    <Grid>

    </Grid>

    <StackPanel Margin="5">        
        <Label Content="Project Item" />
        <TextBlock x:Name="selectionTextBlock" Margin="10,5" />
        <Label Content="kzb file URL" />
        <TextBox x:Name="kzbUrlTextBox" Margin="10,5" IsReadOnly="True" />
    </StackPanel>

Build and run the plugin. See Building and running a Kanzi Studio plugin.
Select in the Project a node or in the Library a resource. The plugin window shows the kzb file URL of the selected project item.

Creating Kanzi Studio window plugins

Creating the base for a Kanzi Studio window plugin

Building and running a Kanzi Studio plugin

Debugging a Kanzi Studio plugin

Adding functionality to your Kanzi Studio plugin

See also